Pemulihan Kesalahan React useActionState: Strategi Penanganan Kesalahan Aksi yang Komprehensif

Di dunia pengembangan web, pengalaman pengguna sebuah formulir adalah titik sentuh yang krusial. Formulir yang mulus dan intuitif dapat menghasilkan konversi yang sukses, sementara yang membuat frustrasi dapat menyebabkan pengguna meninggalkan tugas sepenuhnya. Dengan diperkenalkannya Server Actions dan hook baru useActionState di React 19, para pengembang memiliki alat yang kuat untuk mengelola pengiriman formulir dan transisi state. Namun, sekadar menampilkan pesan kesalahan saat suatu aksi gagal sudah tidak cukup lagi.

Aplikasi yang benar-benar tangguh mengantisipasi kegagalan dan menyediakan jalur pemulihan yang jelas bagi pengguna. Apa yang terjadi ketika koneksi jaringan terputus? Atau ketika input pengguna gagal validasi di sisi server? Apakah pengguna kehilangan semua data yang baru saja mereka ketik selama beberapa menit? Di sinilah strategi penanganan dan pemulihan kesalahan yang canggih menjadi penting.

Panduan komprehensif ini akan membawa Anda melampaui dasar-dasar useActionState. Kita akan menjelajahi strategi lengkap untuk menangani kesalahan aksi, mempertahankan input pengguna, dan menciptakan formulir yang tangguh dan ramah pengguna yang berkinerja andal untuk audiens global. Kita akan beralih dari teori ke implementasi praktis, membangun sistem yang kuat dan mudah dipelihara.

Apa itu `useActionState`? Tinjauan Singkat

Sebelum mendalami strategi pemulihan kita, mari kita tinjau sejenak hook useActionState (yang dikenal sebagai useFormState pada versi eksperimental React sebelumnya). Tujuan utamanya adalah untuk mengelola state dari sebuah aksi formulir, termasuk state tertunda (pending) dan data yang dikembalikan dari server.

Hook ini menyederhanakan pola yang sebelumnya memerlukan kombinasi useState, useEffect, dan manajemen state manual untuk menangani pengiriman formulir.

Sintaks dasarnya adalah sebagai berikut:

            const [state, formAction, isPending] = useActionState(action, initialState);

            

              
                Copy
              
            
          

• action: Fungsi aksi server yang akan dieksekusi. Fungsi ini menerima state sebelumnya dan data formulir sebagai argumen.
• initialState: Nilai yang Anda inginkan untuk state awal, sebelum aksi pernah dipanggil.
• state: State yang dikembalikan oleh aksi setelah selesai. Pada render awal, ini adalah initialState.
• formAction: Aksi baru yang Anda teruskan ke prop action elemen <form> Anda. Ketika aksi ini dipanggil, ia akan memicu action asli, memperbarui flag isPending, dan memperbarui state dengan hasilnya.
• isPending: Sebuah boolean yang bernilai true saat aksi sedang berlangsung, dan false sebaliknya. Ini sangat berguna untuk menonaktifkan tombol submit atau menampilkan indikator pemuatan.

Meskipun hook ini adalah primitif yang fantastis, kekuatan sejatinya terbuka ketika Anda merancang sistem yang tangguh di sekitarnya.

Tantangan: Melampaui Tampilan Kesalahan Sederhana

Implementasi paling umum dari penanganan kesalahan dengan useActionState melibatkan aksi server yang mengembalikan objek kesalahan sederhana, yang kemudian ditampilkan di UI. Sebagai contoh:

            // Aksi server yang sederhana, namun terbatas
export async function updateUser(prevState, formData) {
  const name = formData.get('name');
  if (name.length < 3) {
    return { success: false, message: 'Nama harus memiliki panjang minimal 3 karakter.' };
  }
  // ... perbarui pengguna di DB
  return { success: true, message: 'Profil diperbarui!' };
}

            

              
                Copy
              
            
          

Ini berhasil, tetapi memiliki keterbatasan signifikan yang menyebabkan pengalaman pengguna yang buruk:

• Input Pengguna Hilang: Ketika formulir dikirim dan terjadi kesalahan, browser me-render ulang halaman dengan hasil yang di-render oleh server. Jika bidang input tidak terkontrol (uncontrolled), data apa pun yang dimasukkan pengguna mungkin hilang, memaksa mereka untuk memulai dari awal. Ini adalah sumber utama frustrasi pengguna.
• Tidak Ada Jalur Pemulihan yang Jelas: Pengguna melihat pesan kesalahan, tetapi apa selanjutnya? Jika ada beberapa bidang, mereka tidak tahu mana yang salah. Jika itu adalah kesalahan server, mereka tidak tahu apakah harus mencoba lagi sekarang atau nanti.
• Ketidakmampuan Membedakan Kesalahan: Apakah kesalahan disebabkan oleh input yang tidak valid (kesalahan level 400), kerusakan di sisi server (kesalahan level 500), atau kegagalan otentikasi? String pesan sederhana tidak dapat menyampaikan konteks ini, yang krusial untuk membangun respons UI yang cerdas.

Untuk membangun aplikasi tingkat perusahaan yang profesional, kita memerlukan pendekatan yang lebih terstruktur dan tangguh.

Strategi Pemulihan Kesalahan yang Tangguh dengan `useActionState`

Strategi kami dibangun di atas tiga pilar fundamental: respons aksi yang terstandardisasi, manajemen state yang cerdas di klien, dan UI yang berpusat pada pengguna yang memandu pemulihan.

Langkah 1: Mendefinisikan Bentuk Respons Aksi yang Terstandardisasi

Konsistensi adalah kunci. Langkah pertama adalah menetapkan sebuah kontrak—struktur data yang konsisten yang akan dikembalikan oleh setiap aksi server. Prediktabilitas ini memungkinkan komponen frontend kita untuk menangani hasil aksi apa pun tanpa logika kustom untuk masing-masing aksi.

Berikut adalah bentuk respons yang tangguh yang dapat menangani berbagai skenario:

            // Definisi tipe untuk respons terstandardisasi kita
interface ActionResponse {
  success: boolean;
  message?: string; // Untuk umpan balik global yang dihadapi pengguna (misalnya, notifikasi toast)
  errors?: Record | null; // Kesalahan validasi khusus bidang
  errorType?: 'VALIDATION' | 'SERVER_ERROR' | 'AUTH_ERROR' | 'NOT_FOUND' | null;
  data?: T | null; // Muatan data saat berhasil
}

            

              
                Copy
              
            
          

• success: Sebuah boolean yang jelas menunjukkan hasil.
• message: Pesan global yang dapat dibaca manusia. Ini sempurna untuk toast atau banner seperti "Profil berhasil diperbarui" atau "Tidak dapat terhubung ke server."
• errors: Sebuah objek di mana kunci sesuai dengan nama bidang formulir (misalnya, 'email') dan nilainya adalah array string kesalahan. Ini memungkinkan untuk menampilkan beberapa kesalahan per bidang.
• errorType: String seperti enum yang mengkategorikan kesalahan. Inilah saus rahasia yang memungkinkan UI kita bereaksi secara berbeda terhadap mode kegagalan yang berbeda.
• data: Sumber daya yang berhasil dibuat atau diperbarui, yang dapat digunakan untuk memperbarui UI atau mengarahkan pengguna.

Contoh Respons Sukses:

            { 
  success: true, 
  message: 'Profil pengguna berhasil diperbarui!',
  data: { id: '123', name: 'John Doe', email: 'john.doe@example.com' }
}

            

              
                Copy
              
            
          

Contoh Respons Kesalahan Validasi:

            { 
  success: false, 
  message: 'Harap perbaiki kesalahan di bawah ini.',
  errors: {
    email: ['Silakan masukkan alamat email yang valid.'],
    password: ['Kata sandi harus memiliki panjang minimal 8 karakter.', 'Kata sandi harus mengandung angka.']
  },
  errorType: 'VALIDATION'
}

            

              
                Copy
              
            
          

Contoh Respons Kesalahan Server:

            { 
  success: false, 
  message: 'Terjadi kesalahan tak terduga. Tim kami telah diberi tahu. Silakan coba lagi nanti.',
  errors: null,
  errorType: 'SERVER_ERROR'
}

            

              
                Copy
              
            
          

Langkah 2: Merancang State Awal Komponen

Dengan bentuk respons kita yang telah didefinisikan, state awal yang diteruskan ke useActionState harus mencerminkannya. Ini memastikan konsistensi tipe dan mencegah kesalahan runtime saat mengakses properti yang tidak ada pada render awal.

            const initialState = {
  success: false,
  message: '',
  errors: null,
  errorType: null,
  data: null
};

            

              
                Copy
              
            
          

Langkah 3: Mengimplementasikan Aksi Server

Sekarang, mari kita implementasikan aksi server yang mematuhi kontrak kita. Kita akan menggunakan pustaka validasi populer zod untuk mendemonstrasikan penanganan kesalahan validasi dengan bersih.

            'use server';

import { z } from 'zod';

// Definisikan skema validasi
const profileSchema = z.object({
  name: z.string().min(3, { message: 'Nama harus memiliki panjang minimal 3 karakter.' }),
  email: z.string().email({ message: 'Silakan masukkan alamat email yang valid.' }),
});

// Aksi server mematuhi respons terstandardisasi kita
export async function updateUserProfileAction(previousState, formData) {
  const validatedFields = profileSchema.safeParse({
    name: formData.get('name'),
    email: formData.get('email'),
  });

  // Tangani kesalahan validasi
  if (!validatedFields.success) {
    return {
      success: false,
      message: 'Validasi gagal. Silakan periksa bidang-bidang ini.',
      errors: validatedFields.error.flatten().fieldErrors,
      errorType: 'VALIDATION',
      data: null
    };
  }

  try {
    // Simulasikan operasi database
    console.log('Memperbarui pengguna:', validatedFields.data);
    // const updatedUser = await db.user.update(...);
    
    // Simulasikan potensi kesalahan server
    if (validatedFields.data.email.includes('fail')) {
      throw new Error('Koneksi database gagal');
    }

    return {
      success: true,
      message: 'Profil berhasil diperbarui!',
      errors: null,
      errorType: null,
      data: validatedFields.data
    };
  } catch (error) {
    console.error('Kesalahan Server:', error);
    return {
      success: false,
      message: 'Terjadi kesalahan server internal. Silakan coba lagi nanti.',
      errors: null,
      errorType: 'SERVER_ERROR',
      data: null
    };
  }
}

            

              
                Copy
              
            
          

Aksi ini sekarang menjadi fungsi yang dapat diprediksi dan tangguh. Ini secara jelas memisahkan logika validasi dari logika bisnis dan menangani kesalahan tak terduga dengan baik, selalu mengembalikan respons yang dapat dipahami oleh frontend kita.

Membangun UI: Pendekatan Berpusat pada Pengguna

Sekarang untuk bagian terpenting: menggunakan state terstruktur ini untuk menciptakan pengalaman pengguna yang superior. Tujuan kita adalah untuk memandu pengguna, bukan hanya memblokir mereka.

Pengaturan Komponen Inti

Mari kita siapkan komponen formulir kita. Kunci untuk mempertahankan input pengguna saat terjadi kegagalan adalah dengan menggunakan komponen terkontrol (controlled components). Kita akan mengelola state input dengan useState. Ketika pengiriman formulir gagal, komponen akan di-render ulang, tetapi karena nilai input disimpan dalam state React, nilai-nilai tersebut tidak hilang.

            'use client';

import { useState } from 'react';
import { useActionState } from 'react';
import { updateUserProfileAction } from './actions';

const initialState = { success: false, message: '', errors: null, errorType: null };

export function UserProfileForm({ user }) {
  const [state, formAction, isPending] = useActionState(updateUserProfileAction, initialState);

  // Gunakan useState untuk mengontrol input formulir dan mempertahankannya saat re-render
  const [name, setName] = useState(user.name);
  const [email, setEmail] = useState(user.email);

  return (
    

      
Edit Profil

      {/* Banner Pesan Kesalahan/Sukses Global */}
      {state.message && (
        

          {state.message}
        
      )}

      

        Nama
         setName(e.target.value)}
          aria-invalid={!!state.errors?.name}
          aria-describedby="name-error"
        />
        {state.errors?.name && (
          
{state.errors.name[0]}
        )}
      

      

        Email
         setEmail(e.target.value)}
          aria-invalid={!!state.errors?.email}
          aria-describedby="email-error"
        />
        {state.errors?.email && (
          
{state.errors.email[0]}
        )}
      

      
        {isPending ? 'Menyimpan...' : 'Simpan Perubahan'}
      
    
  );
}

            

              
                Copy
              
            
          

Detail Implementasi UI Utama:

• Input Terkontrol: Dengan menggunakan useState untuk name dan email, nilai input dikelola oleh React. Ketika aksi server gagal dan komponen di-render ulang dengan state kesalahan yang baru, variabel state name dan email tetap tidak berubah, sehingga mempertahankan input pengguna dengan sempurna. Ini adalah teknik terpenting untuk pengalaman pemulihan yang baik.
• Banner Pesan Global: Kita menggunakan state.message untuk menampilkan pesan di tingkat atas. Kita bahkan bisa mengubah warnanya berdasarkan state.success.
• Kesalahan Khusus Bidang: Kita memeriksa state.errors?.fieldName dan, jika ada, me-render pesan kesalahan tepat di bawah input yang relevan.
• Aksesibilitas: Kita menggunakan aria-invalid untuk secara terprogram menunjukkan kepada pembaca layar bahwa sebuah bidang memiliki kesalahan. aria-describedby menghubungkan input dengan pesan kesalahannya, memastikan teks kesalahan dibacakan ketika pengguna fokus pada bidang yang tidak valid.
• State Tertunda (Pending): Boolean isPending digunakan untuk menonaktifkan tombol submit, mencegah pengiriman ganda dan memberikan umpan balik visual yang jelas bahwa sebuah operasi sedang berlangsung.

Pola Pemulihan Tingkat Lanjut

Dengan fondasi kita yang kokoh, kita sekarang dapat mengimplementasikan pengalaman pengguna yang lebih canggih berdasarkan jenis kesalahan.

Menangani Jenis Kesalahan yang Berbeda

Bidang errorType kita sekarang sangat berguna. Kita dapat menggunakannya untuk me-render komponen UI yang sama sekali berbeda untuk skenario kegagalan yang berbeda.

            function ErrorRecoveryUI({ state, onRetry }) {
  if (!state.errorType) return null;

  switch (state.errorType) {
    case 'VALIDATION':
      // Untuk validasi, umpan balik utama adalah kesalahan bidang inline,
      // jadi kita mungkin tidak memerlukan komponen khusus di sini. Pesan global sudah cukup.
      return 
Harap tinjau bidang yang ditandai dengan warna merah.
;
    
    case 'SERVER_ERROR':
      return (
        

          
Terjadi Kesalahan Server
          
{state.message}
          Coba Lagi
        
      );
    
    case 'AUTH_ERROR':
       return (
        

          
Sesi Kedaluwarsa
          
Sesi Anda telah berakhir. Silakan login kembali untuk melanjutkan.
          Ke Halaman Login
        
      );

    default:
      return 
{state.message}
;
  }
}

// Dalam return komponen utama Anda:

  {/* ... bidang formulir ... */}
   { /* logika untuk mengaktifkan kembali formulir */ }} />
  Simpan


            

              
                Copy
              
            
          

Mengimplementasikan Mekanisme "Coba Lagi"

Untuk kesalahan yang dapat dipulihkan seperti SERVER_ERROR, tombol "Coba Lagi" adalah UX yang sangat baik. Bagaimana cara kita mengimplementasikannya? `formAction` terikat pada event submit formulir. Pendekatan sederhana adalah dengan membuat tombol "Coba Lagi" mengatur ulang state aksi dan mengaktifkan kembali formulir, mengundang pengguna untuk mengklik tombol submit utama lagi.

Karena useActionState tidak menyediakan fungsi `reset`, pola umum adalah membungkusnya dalam hook kustom atau mengelolanya dengan menyebabkan komponen di-render ulang dengan kunci (key) baru, meskipun seringkali pendekatan paling sederhana adalah hanya memandu pengguna.

Solusi pragmatis: Input pengguna sudah dipertahankan. Flag `isPending` akan bernilai false. "Coba lagi" yang terbaik adalah dengan hanya mengizinkan pengguna untuk mengklik tombol submit asli lagi. UI dapat dengan mudah memandu mereka:

Untuk SERVER_ERROR, UI kita dapat menampilkan pesan kesalahan: "Terjadi kesalahan. Perubahan Anda telah disimpan. Silakan coba kirim lagi." Tombol submit sudah diaktifkan karena `isPending` bernilai false. Ini tidak memerlukan manajemen state yang kompleks.

Menggabungkan dengan useOptimistic

Untuk nuansa yang lebih responsif, useActionState berpasangan dengan indah dengan hook useOptimistic. Anda dapat mengasumsikan aksi akan berhasil dan memperbarui UI secara instan. Jika aksi gagal, useActionState akan menerima state kesalahan, yang akan memicu re-render dan secara otomatis mengembalikan pembaruan optimis ke state yang sebenarnya.

Ini di luar cakupan pembahasan mendalam tentang penanganan kesalahan ini, tetapi ini adalah langkah logis berikutnya dalam menciptakan pengalaman pengguna yang benar-benar modern dengan React Actions.

Pertimbangan Global untuk Aplikasi Internasional

Saat membangun untuk audiens global, melakukan hardcoding pesan kesalahan dalam bahasa Inggris bukanlah pilihan yang layak.

Internasionalisasi (i18n)

Struktur respons terstandardisasi kami dapat dengan mudah diadaptasi untuk internasionalisasi. Alih-alih mengembalikan string `message` yang di-hardcode, server harus mengembalikan kunci atau kode pesan.

Respons Server yang Dimodifikasi:

            {
  success: false,
  messageKey: 'errors.validation.checkFields',
  errors: {
    email: ['errors.validation.email.invalid'],
  },
  errorType: 'VALIDATION'
}

            

              
                Copy
              
            
          

Di sisi klien, Anda akan menggunakan pustaka seperti react-i18next atau react-intl untuk menerjemahkan kunci-kunci ini ke dalam bahasa yang dipilih pengguna.

            import { useTranslation } from 'react-i18next';

// Di dalam komponen Anda
const { t } = useTranslation();

// ...

{state.messageKey && 
{t(state.messageKey)}
}

// ...

{state.errors?.email && 
{t(state.errors.email[0])}
}

            

              
                Copy
              
            
          

Ini memisahkan logika aksi Anda dari lapisan presentasi, membuat aplikasi Anda lebih mudah dipelihara dan diterjemahkan ke bahasa baru.

Kesimpulan

Hook useActionState lebih dari sekadar kemudahan; ini adalah bagian fundamental untuk membangun aplikasi web modern dan tangguh di React. Dengan melampaui tampilan pesan kesalahan dasar dan mengadopsi strategi pemulihan kesalahan yang komprehensif, Anda dapat secara dramatis meningkatkan pengalaman pengguna.

Mari kita rekapitulasi prinsip-prinsip utama dari strategi kita:

1. Standarisasi Respons Server Anda: Buat struktur JSON yang konsisten untuk semua aksi Anda. Kontrak ini adalah landasan perilaku frontend yang dapat diprediksi. Sertakan errorType yang berbeda untuk membedakan antara mode kegagalan.
2. Pertahankan Input Pengguna dengan Segala Cara: Gunakan komponen terkontrol (useState) untuk mengelola nilai bidang formulir. Ini mencegah kehilangan data saat terjadi kegagalan pengiriman dan merupakan landasan dari pengalaman pengguna yang memaafkan.
3. Berikan Umpan Balik Kontekstual: Gunakan state kesalahan terstruktur Anda untuk menampilkan pesan global, kesalahan bidang inline, dan UI yang disesuaikan untuk berbagai jenis kesalahan (misalnya, validasi vs. kesalahan server).
4. Bangun untuk Audiens Global: Pisahkan pesan kesalahan dari logika server Anda menggunakan kunci internasionalisasi, dan selalu pertimbangkan standar aksesibilitas (atribut ARIA) untuk memastikan formulir Anda dapat digunakan oleh semua orang.

Dengan berinvestasi dalam strategi penanganan kesalahan yang tangguh, Anda tidak hanya memperbaiki bug—Anda membangun kepercayaan dengan pengguna Anda. Anda menciptakan aplikasi yang terasa stabil, profesional, dan menghargai waktu serta usaha mereka. Saat Anda terus membangun dengan React Actions, biarkan kerangka kerja ini memandu Anda dalam menciptakan pengalaman yang tidak hanya fungsional tetapi juga benar-benar menyenangkan untuk digunakan, di mana pun pengguna Anda berada di seluruh dunia.